This document describes the examples that illustrate the scenarios described in the guide Cloud Design Patterns (see http://aka.ms/Cloud-Design-Patterns). Each example is a Microsoft Visual Studio 2012 project that you can compile and run.

Before you start

Ensure that you have installed all of the software prerequisites. For details see the Release Notes.

Each example is a separate project. The folders of the examples also contain code snippets that demonstrate some of the patterns in the guide. These are not projects that can be run, but are included so that you can easily view and reuse the code in your own solutions.

The examples demonstrate operational aspects of applications running in Windows Azure. Therefore, you will need to use the diagnostics tools in order to understand how each code sample works. You must ensure that the web and worker roles in each solution are configured to use the diagnostics mechanism. If not, you will not see the trace information generated by each example.

Running the Examples

You can run all of the examples locally in the Visual Studio Windows Azure emulator. You can also run most of the examples by deploying them to a Windows Azure Cloud Service.

• Start Visual Studio using an account that has Administrator privileges ("Run as Administrator").
• Open the solution you want to explore from the subfolders where you downloaded the examples.
• Right-click on each role in Solution Explorer, select Properties, and ensure that the role is configured to generate diagnostic information.
• Follow any additional steps shown in the list of examples to set up that example.


• If you want to run the example in the local Windows Azure emulator:
• Press F5 in Visual Studio to start the example running.
• Open the Windows Azure Compute Emulator UI from the icon in the notification area.
• Select each role in turn and view the diagnostic information generated by Trace statements in the code.
• If you want to run the example on Windows Azure:
• Provision a Windows Azure Cloud Service and deploy the application to it from Visual Studio.
• Open the Server Explorer Window in Visual Studio and expand the Windows Azure entry.
• Expand Cloud Services and then expand the entry for the solution you deployed.
• Right-click each role instance and select View Diagnostics Data to see the diagnostic information generated by Trace statements in the code. This is written to the WADLogsTable in the Storage/Development/Tables section.

Configuring Service Bus for the Examples

Some of the examples use a Windows Azure Service Bus to send and receive messages. Check the details of each example shown below to see if this is required. Where it is required. you must:

• Provision a Windows Azure Service Bus Namespace
• Edit the ServiceBus.ConnectionString setting by changing "[SERVICE BUS CONNECTION STRING]" to your own Service Bus endpoint in the following files for every role in the solution:
• ServiceConfiguration.Cloud.csfg if you will run the example on Windows Azure.
• ServiceConfiguration.Local.csfg if you will run the example in the Windows Azure Emulator.
  (you can update settings by right-clicking on each of the roles and selecting Properties, or by editing the files directly in the main Visual Studio window.)

About the Examples

Each example is a separate project within the solution. The folders of the solution also contain code snippets that demonstrate some of the patterns in the guide. These are not projects that can be run, but are included so that you can easily view and reuse the code in your own solutions.

The examples you can run are:

The code snippets for other patterns can be found in the root folder of the examples.

Competing Consumers. This example contains two components: the Sender worker role is responsible for sending messages to a Service Bus queue, and the Receiver worker role retrieves messages from the queue and processes them. The Receiver worker role is configured to run with two instances to simulate competition between consumers.

• Before running this example, configure a Windows Azure Service Bus Namespace as shown above.

Compute Resource Consolidation. This example shows how you can consolidate several separate and distinct tasks into a single worker role. There are no additional requirements for running this example.

External Configuration Store. This example shows a mechanism for storing configuration settings in an external store instead of using configuration files. In this example, settings are stored in Windows Azure Blob Storage. The blob containing the configuration information is monitored by an instance of the ExternalConfigurationManager class. When the ExternalConfigurationManager object detects a change in the configuration store, it notifies the application of the change.

• This example can be run only in the local Windows Azure emulator.
• To simulate an external update to the configuration blob:
• Open the NewConfiguration folder. This contains a version of the configuration blob with different values.
• Upload this blob to the local Windows Azure emulator storage to replace the original. You can do this in the Storage section of Visual Studio Server Explorer.
• View the Output Window to see the changes detected by the ExternalConfigurationManager.

Health Endpoint Monitoring. This example shows how you can set up a web endpoint that checks the health of dependent services by returning appropriate status codes. The endpoints are designed to be consumed by a watchdog monitoring service such as Windows Azure Endpoint Monitoring, but you can open and invoke the endpoint operations from a browser to see the results. You can also deploy and configure your own endpoint monitoring tool of choice to send requests to the service operations and analyze the responses received.

• Start the example running and navigate to one of the monitoring endpoints. Use the F12 Developer Tools in Internet Explorer or the equivalent in your browser to watch the network traffic response pattern.
• The response will be 200 (OK), or a 500 error code that indicates a problem with a service.
• The sample contains four endpoints that you can test:
• /HealthCheck/CoreServices This is a simple check on dependent services to determine if they are responding.
• /HealthCheck/ObscurePath/{path} This demonstrates a check operation that uses a configurable obscure path defined in the service configuration file. Replace path with the value of the setting named Test.ObscurePathfrom in the file ServiceConfiguration.*.csfg. Note that this technique is not to be used as an alternative to properly securing an application and implementing authentication.
• /HealthCheck/CheckUnstableServiceHealth This will randomly return a 500 exception for approximately 20% of the requests.
• /HealthCheck/TestResponseFromConfig This returns a response code set in configuration (.cscfg) for testing. Deploy the solution with endpoint monitoring configured to use this operation, and then explicitly set the "Test.ReturnStatusCode" setting to return the required status code to test and demonstrate the effects of these codes on the monitoring service.

Leader Election. This example shows how a worker role instance can become a leader among a group of peer instances. The leader can then perform tasks that coordinate and control the other instances; these tasks should be performed by only one instance of the worker role. The leader is elected by acquiring a blob lease. There are no additional requirements for running this example.

Pipes and Filters. This example contains two filters that could perform some part of the overall processing for a task. The two filters are combined into a pipeline; the output of one filter is passed as the input to the next. The filters are implemented as separate worker roles and a Windows Azure Service Bus queue provides the infrastructure that acts as the pipe.

• Before running this example, configure a Windows Azure Service Bus Namespace as shown above.

Priority Queue. This example shows how you can implement priority queues by using Service Bus Topics and Subscriptions. A worker role is responsible for sending messages to a topic. It assigns a priority to each message. The receiving worker roles read messages from subscriptions that have the corresponding priority. In the example, The PriorityQueue.High worker role runs with two instances, whereas the PriorityQueue.Low worker runs only with one. This ensures that high priority messages are read from the queue more quickly than low priority messages.

• Before running this example, configure a Windows Azure Service Bus Namespace as shown above.

Runtime Reconfiguration. This example shows how a change in the settings of a Cloud Service can be applied without restarting the web or worker role. The relevant code is in the files Global.asax.cs and WebRole.cs.

• If you intend to run the example in the local Windows Azure emulator:
• Start the application without debugging by selecting Start Without Debugging from the DEBUG menu.
• In the folder samples-folder\RuntimeReconfiguration\bin\Debug (where samples-folder is the folder where you installed the examples) open the file ServiceConfiguration.cscfg in Visual Studio or in a text editor.
• Change the value of the setting named CustomSetting to a different value.
• To indicate to the emulator that the configuration has changed, open a Windows Azure Command Prompt from the Windows Start screen or Apps page.
• In Command Prompt type the command csrun /status and make a note of the value of Deployment-Id.
• In Command Prompt type the following command on one line:
    csrun /update:deployment-id;samples-folder\RuntimeReconfiguration\bin\Debug\ServiceConfiguration.cscfg
  replacing deployment-id and samples-folder with your own values.
• Wait for a few seconds to allow the reconfiguration to complete.
• In the browser, view the values that were updated without restarting the application. Note that, due to some issues with the compute emulator, the first time you run execute the csrun /update command it will restart the instance. After that it will re-configure the application without restarting it.
• If you intend to run the example on Windows Azure:
• Deploy the application to Windows Azure from Visual Studio and start it running.
• Open the Windows Azure portal, sign into your subscription, and select the Cloud Service where you deployed the application.
• Using the portal to change the value of the setting named CustomSetting in the service configuration to a different value.
• Wait for a few seconds to allow the reconfiguration to complete.
• In the browser, view the values that were updated without restarting the application.

Static Content Hosting. This example shows how to reference static content from a publicly accessible storage service. The example contains a Windows Azure web role, which hosts a web application that references JavaScript files and images deployed to a Windows Azure storage account. This type of content is typically deployed to the storage account as part of the application deployment process. However, to simplify the example, these files are deployed to the storage account when the application starts up.

    The JavaScript and stylesheet content is referenced in the file App_Start\BundleConfig.cs by using a CDN URL. The image content is referenced in the file Views\Home\Index.cshtml. The URLs are generated by an HTML helper class implemented in the file StaticContentUrlHtmlHelper.cs.

    When running the application in release mode, you should note that these static resources are served out of the storage account, as opposed to being delivered by the application server.

• This example is designed to run by default in the local Windows Azure emulator. If you want to run it on Windows Azure you must:
• Provision a Windows Azure storage account.
• Update the file ServiceConfiguration.Cloud.cscfg by changing the value of the StaticContent.StorageConnectionString setting to the connection string for your storage account. You can do this in the Properties page for the role or by opening the file in the main Visual Studio window.

Valet Key. This example shows how a client application can obtain a shared access signature with the necessary permissions to write directly to blob storage. For simplicity, this sample focuses on the mechanism to obtain and consume a valet key and does not show how to implement authentication or secure communications.

• Start the Web Service and note the URL of the web role shown in the browser address bar.
• Open the file app.config from the ValetKey.Client project and change the setting for serviceEndpointUrl to   [your-URL]/api/values/
• By default this is set to http://127.0.0.1:81/api/values/
• Start a new instance of the ValetKey.Client project to upload the blob.
  • Right-click the project, select Debug, and click Start new instance.
• View the Trace information to see what the code does.